🤖 AI Code Review

共审查 10 个变更文件
⚠️ 另有 20 个文件超过上限（最多 10 个）未审查

📁 .github/workflows/linux-reproduction-docs.yml

🔴 Possibly broken: pytest==9.1.1 — pytest 9.x did not exist on PyPI at the time of writing (8.x was current). If this version doesn't exist, pip install fails hard and the workflow is red on every PR.
Suggestion: Verify the version exists; consider pinning to a known-good release, or drop the pin and use a requirements-test.txt in the repo so dependency drift is reviewed like code.

🟡 Inconsistent supply-chain pinning — setup-python is pinned to a full commit SHA, but actions/checkout@v4 floats on a tag.
Suggestion: Pin checkout to a SHA too, or (if you prefer tag-level) apply the same policy to setup-python. The inconsistency signals that the pinning convention isn't documented or enforced.

🟡 No push trigger — The check only runs on pull_request. A force-push or admin push directly to main bypasses it entirely.
Suggestion:

on:
  push:
    branches: [main]
  pull_request:
    # ...

🟡 set -euo pipefail only in one of two run steps — The check_linux_repro_docs.py step has no explicit error handling. GitHub's default shell does set -e, but pipefail and nounset are not set by default.
Suggestion: Either add a reusable shell preamble, or use shell: bash + a common env setup. This matters if the script ever uses pipelines or references an unset variable.

💭 Consider cache: pip in setup-python — Even for a small test suite, it avoids re-downloading on every PR. Negligible here, but it's a one-liner that becomes valuable as the test suite grows.

📁 .github/workflows/llm-deploy.yml

🟡 full-qwen3-frontend downloads ~1.24GB on every PR — No caching. Each PR pays full bandwidth and time for the model download. Consider actions/cache on output/qwen3-full-model/, or gating this job to pull_request only for path-filtered changes and running it on workflow_dispatch/schedule otherwise.

🟡 w2-acceptance needs correct skipped-handling — if: always() + toJSON(needs) means check_w2_ci_results.py receives full-qwen3-frontend.result as "skipped" when path filters don't match. If that script treats "skipped" as "success", a PR touching only docs could pass W2 acceptance without any actual gate executing. Verify it requires "success" not just "not failure."

🟡 Mixed execution styles for unit gates — unit:frontend-ops runs pytest, unit:backend-ops runs python3 probes/.../run.py directly. The probe produces a report file but no JUnit XML. If the probe script fails silently (non-zero exit but incomplete report), the gate could mask a real failure. Ensure run.py exits non-zero on assertion failures.

💭 unit:runtime (step) has no per-step timeout — Job timeout is 60 min total; add timeout-minutes to the step too for faster feedback on hangs.

💭 Unnecessary quotes on env values — OMP_NUM_THREADS: "1" etc. GitHub Actions always stores env as strings; bare 1 is equivalent and slightly cleaner.

📁 .gitignore

💭 Redundant entry — .venv-linux/ 已被下一行的 .venv-*/ 通配符覆盖，可以移除以避免维护时重复。

📁 CONTRIBUTING.md

🟡 Suggestion — This bullet conflates two distinct policies (platform requirements + historical data preservation). Splitting them improves scannability and makes it easier to update one without touching the other:

- Qwen3 deployment (W1+) requires Linux (Ubuntu 24.04, Bash, Python 3.12,
  Linux tool paths) in all public guides, PR instructions, and CI.
  See [Linux reproduction contract](docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md).
- Preserve the actual platform and commit identity of historical measurements;
  personal dev environments are not acceptance evidence.

💭 Nit — Confirm docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md exists at the referenced path before merging, or the link will be dead.

📁 benchmarks/test_regalloc/regalloc.md

🟡 Windows 指令被完全移除 — 原先的 PowerShell 命令 (Windows PowerShell) 被替换而非保留为备选。如果仓库仍有 Windows 用户，建议在注释中提一句"Windows 用户请参考 X 路径或 pwsh"。

🟡 pip install -e ".[all]" 无前置校验 — 如果用户没在仓库根目录执行（文档虽写了但容易忽略），这步会静默失败。建议加一行 test -f setup.py -o -f pyproject.toml 或类似守卫，避免后续 python -m ... 报错让人误以为是 benchmark 本身有问题。

💭 新增目录无 .gitignore 提示 — .venv-regalloc/ 和 benchmark_reports/ 容易误提交。可在段落末加一句提醒 # 建议将 .venv-regalloc/ 和 benchmark_reports/ 加入 .gitignore。

💭 llvmlite 安装方式未说明 — 文档提到 llvm_available=false 的含义，但没说如何装 llvmlite。如果用户想完整对比，需要 pip install llvmlite，建议补一句。

📁 docs/guide/00-环境搭建指南.md

🔴 Missing redirect for removed platforms — 删除了 macOS/Windows 全部安装说明，但没有留下任何迁移指引。macOS 用户打开此页面会直接死路。建议至少加一行：macOS 用户请参考 [macOS 指南](../path/to/mac-guide.md) 或联系项目维护者，明确告知本项目是否仍支持 macOS。

🔴 Broken reference risk — 新增链接 ../llm-deploy-v1.0/LINUX_REPRODUCTION.md，请确认该路径存在且拼写无误，否则点击即 404。

🟡 Reproduction requirement is buried — "复现记录须保存发行版、CPU、Python 和工具版本" 这条硬性要求嵌在 apt install 段落末尾，容易被读者忽略。建议独立成段或用 > ⚠️ blockquote 突出，并说明 如何 保存（例如 uname -a && python3 --version && gcc --version > repro-env.txt），否则要求等于没写。

🟡 Scope policy misplaced — "个人开发环境不作为 Linux 验收依据" 是验收政策，不是环境搭建步骤。放在"环境搭建指南"的开头会让只想装环境的人困惑。考虑移到项目根目录的 CONTRIBUTING.md 或验收文档中，此页仅留一句摘要 + 链接。

💭 WSL removal may strand existing users — 原指南明确推荐 WSL 给 Windows 用户，现在完全移除没有任何说明。如果确实不再支持 Windows/WSL，建议在删除处加一句 changelog note 或脚注解释原因，避免已有用户困惑。

💭 # Linux / macOS / WSL comment removal — 正确且一致，无需修改。

📁 docs/guide/04-故障排除FAQ.md

💭 Nit: 占位符语义退化 — path/to/resolved-file 看起来像实际路径，用户可能直接复制粘贴，而 <冲突文件> 用尖括号明确表示"请替换"的意图更强。

Suggestion: 改为 git add <冲突文件路径> 或 git add ./resolved-file.txt，保持占位符可辨识。

📁 docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md

🔴 PyYAML pin 可能不可解析 — 第 2 节：PyYAML==6.0.3。上游稳定线目前到 6.0.2，若 6.0.3 不存在，pip install -e . ziglang==0.14.1 PyYAML==6.0.3 会直接失败，而这是整份文档第一个真正执行安装的地方。建议在合并前实跑一次 pip index versions PyYAML 确认；否则换成 6.0.2 或用 >= 加 pip check 兜底。

🔴 SCRATCHV_CC 的推导路径可能拿不到二进制 — 第 2 节：Path(ziglang.__file__).parent / "zig" 假设 zig 可执行文件与包的 __init__.py 同级。较新的 ziglang wheel 把它放在 ziglang/bin/zig。建议改为显式查找：

for c in "$B/zig" "$B/bin/zig"; do [[ -x "$c" ]] && { export SCRATCHV_CC="$c"; break; }; done

或在文档中固定 ziglang 的具体版本布局并加 -e 校验 [[ -x "$SCRATCHV_CC" ]]。

🟡 各代码块不共享环境变量，单独复制会报 unbound variable — 第 3、4 节都用了 $SCRATCHV_PYTHON，但每块以 set -euo pipefail 独立开始，set -u 下未 export 即报错。文中"重新设置环境变量"只覆盖了新终端场景。建议抽一个 env.sh（或 scripts/linux_repro_env.sh）让每块首行 source，既去重也让 CI 复现同一套导出。

🟡 用 FETCH_HEAD 切换削弱了"记录实际 SHA"这条硬约束 — 第 1 节：PR ref 会移动，git switch --detach FETCH_HEAD 靠人自觉记录 SHA。建议改为显式输入：

COMMIT_SHA=<期望的完整 SHA>
git fetch origin "pull/$PR_NUMBER/head"
git switch --detach "$COMMIT_SHA"

并把"与 PR 页面对核"这一步从文档要求升级为命令本身的行为。

🟡 qemu-system-riscv64 缺失时静默退出 — set -e 下 export SCRATCHV_QEMU="$(command -v qemu-system-riscv64)" 失败会直接中断，但没有任何提示，首次安装的用户难以定位。加一行 command -v ... || { echo "...install qemu-system-misc"; exit 1; }。

💭 git lfs install 会写全局 ~/.gitconfig — 在容器/CI 上无感，但个人机器上是有副作用的操作。可考虑 git lfs install --skip-smudge 并在文档里注明这一点。

💭 "W3（含 W3 的版本）" 表头略拗口，建议写成"W3 及后续包含 W3 入口的提交"。

💭 第 2 节 pip install -e . ziglang==0.14.1 PyYAML==6.0.3 把仓库依赖与 pin 混在一条命令里：若 pyproject.toml 也声明了 ziglang/PyYAML 且约束不同，pip 的解析结果与预期不符。建议分开两步安装，并把项目自身的依赖约束作为唯一来源。

📁 docs/llm-deploy-v1.0/W1/IR解释器-使用说明.md

🟡 **文档结构：段落位置打断元数据块** — 新增段落插入在标题和元数据（日期、输入）之间，破坏了标题→元数据的阅读节奏。
建议：将此段移到元数据块之后，或独立为 `## 环境要求` 小节。

🟡 **相对路径需确认** — `../LINUX_REPRODUCTION.md` 相对于当前文件 `docs/llm-deploy-v1.0/W1/` 解析到 `docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md`。请确认该文件确实存在于该路径。

💭 **激活说明可更明确** — "已激活的 `.venv-linux/bin/python`" 对首次阅读者不够自洽，可补一句 `source .venv-linux/bin/activate` 或直接统一写成绝对虚拟环境路径。

📁 docs/llm-deploy-v1.0/W1/IR解释器-开发文档.md

🔴 **可能失效的相对链接** — 新增行：`../LINUX_REPRODUCTION.md`

文档位于 `docs/llm-deploy-v1.0/W1/`，`..` 只回退一层，实际解析到
`docs/llm-deploy-v1.0/LINUX_REPRODUCTION.md`。若该文件放在 `docs/` 根下，
应为 `../../LINUX_REPRODUCTION.md`。
建议：确认目标路径并在 CI 里加 linkcheck，文档链接是本轮唯一新增内容，断了会直接影响交付可信度。

🟡 **`python` 的定义依赖未说明的前置步骤** — 新增行："已激活的 `.venv-linux/bin/python`"

Ubuntu 24.04 默认没有 `python`（需 `python-is-python3`），所以"激活 venv 后才有 `python`"是隐含前提，但本 diff 未给出 `source .venv-linux/bin/activate` 之类命令。
建议：明确写成"以下命令假设已执行 `source .venv-linux/bin/activate`（`.venv-linux` 构建方式见复现约定）"，避免读者在裸 shell 下执行全文失败。

🟡 **"交付 v1.0"与文内元数据 v0.1 冲突** — 第 5 行：`> 版本：v0.1，开发说明；本轮实现已落地`

新段落把适用范围声明为"正式交付、CI"，但目录是 `llm-deploy-v1.0`、文内仍写 v0.1 且"开发说明"。交付物出现版本号不一致会让复现者不确定以哪个为准。
建议：既然指向正式交付，同步把版本行改为 v1.0（或在版本行注明"目录版本 v1.0，本文档 v0.1"）。

🟡 **环境要求只约束了三样，边界不清** — 新增行：Ubuntu 24.04 x86_64 / Bash / Python 3.12

未说明 Python 是否要求具体补丁版本（3.12.x）、pip 依赖锁文件位置、GPU/CUDA 是否必需。若 IR 解释器是纯 CPU 的，建议在句尾加一句"不依赖 GPU"，否则读者会误判资源要求。
建议：补充 `requirements.txt`/锁文件路径与 GPU 依赖结论，或把这些内容下沉到复现约定并在本行只留一句指引。

💭 **新增段落插在元数据块之前，破坏原有可读性约定**

原文结构是标题 → 元数据（版本/日期/依据）→ 正文。新段落在标题后立即出现，把元数据挤到第二位，元数据反而不如开头那段环境说明醒目。
建议：移到元数据 blockquote 之后，或独立成"## 环境要求"小节，既保留元数据位置，也让环境信息有可跳转锚点。

💭 **一句话混了两个概念，建议拆分**

"正式交付、CI 和他人复现使用 ……；命令中的 `python` 指 ……"前半句是适用范围，后半句是命令约定，两者无必然联系。
建议：拆为两条，命令约定更适合放在每节命令示例首次出现处或"## 环境要求"里，而不是文档顶部。

⚠️ 未审查的文件

• docs/llm-deploy-v1.0/W1/IR解释器-设计文档.md
• docs/llm-deploy-v1.0/W1/README.md
• docs/llm-deploy-v1.0/W1/W1-执行计划.md
• docs/llm-deploy-v1.0/W1/W1-探测方案.md
• docs/llm-deploy-v1.0/W1/W1-本地收尾与审查报告.md
• docs/llm-deploy-v1.0/W1/interfaces.md
• docs/llm-deploy-v1.0/W1/risks.md
• docs/llm-deploy-v1.0/W1/算子补齐与单测-benchmark.html
• docs/llm-deploy-v1.0/W1/算子补齐与单测-benchmark.json
• docs/llm-deploy-v1.0/W1/算子补齐与单测-benchmark.md
• docs/llm-deploy-v1.0/W1/算子补齐与单测报告.txt
• docs/llm-deploy-v1.0/W2/README.md
• docs/llm-deploy-v1.0/W2/W1修复与W2本地验收报告.md
• docs/llm-deploy-v1.0/W2/W2-分支验收与发布说明.md
• docs/llm-deploy-v1.0/开发计划.md
• docs/topics/06-性能基准套件/06-性能测试套件使用说明.md
• docs/topics/06-性能基准套件/06-性能测试套件设计文档.md
• docs/topics/09-DSL错误提示美化器/09-DSL错误提示美化器-CI与Benchmark.md
• docs/topics/09-DSL错误提示美化器/09-DSL错误提示美化器-开发文档.md
• docs/topics/17-寄存器分配/17-寄存器分配-Benchmark设计文档.md